namespace FineCollection.Intf
{
    /// <summary>
    /// A stack.
    /// </summary>
    /// <typeparam name="T">type of an item.</typeparam>
    public interface WStack<T> : RList<T>
    {
        /// <summary>
        /// Pushs the item (adds the item onto the top of the stack).
        /// </summary>
        /// <param name="item">item to push.</param>
        void Push(T item);


        /// <summary>
        /// Pops an item (excludes the item from the top of the stack
        /// and returns the excluded item).
        /// </summary>
        /// <returns>excluded item.</returns>
        /// <exception cref="CollectionIsEmptyException">if the stack is empty.</exception>
        T Pop();


        /// <summary>
        /// The top item without excluding it from the stack.
        /// </summary>
        /// <exception cref="CollectionIsEmptyException">if the stack is empty.</exception>
        T Top { get; }


        /// <summary>
        /// Returns the <i>i</i>-th item from the top without excluding.
        /// </summary>
        /// <param name="index">1 - the top item, 2 - the item under the top, ..., <c>Count</c> - the bottom item.</param>
        /// <returns>the required item.</returns>
        /// <exception cref="CollectionIsEmptyException">if the stack is empty.</exception>
        T Peek(int index);

    }
}